home *** CD-ROM | disk | FTP | other *** search
Text File | 1993-12-03 | 69.4 KB | 1,648 lines |
-
- ----------------------------------------------
- Angie 3.6 (3.12.93) © Franz Schwarz - Giftware
- ----------------------------------------------
-
- ANother Great Intuition Enhancer - Commodity
-
- Written & © 1993 by
- Franz Schwarz
- Mühlenstraße 2
- D-78591 Durchhausen, Germany
- Uucp: Franz_Schwarz@mil.ka.sub.org
- Fido Classic: 2:2476/506.18
-
- GUI created with assistance of GadToolsBox 37.300
-
- Due to Angie being GIFTWARE, thou shalt send the author a
- nice present, cash, or AT LEAST a postcard, if you use it.
-
- Gifts, the author appreciates very much include music tapes,
- CDs & LPs of pop/rock/indie/blues/soul music. So, if
- you have any music volumes you can spare,
- don't hesitate and send them to the author;-)
-
-
- Moreover, Angie is TOLERANCEWARE.
- In other words, it is strictly forbidden for persons that
- support or approve acts of violence against other people
- because of their race, descent, skin color, gender, sexual
- orientation, religion or handicap to use or take profit
- of this software package in any way whatsoever.
-
-
- table of contents
- -----------------
-
- preface
-
- concepts, program design
-
- ATTN. lazy boys and girls - WHAT EVERYONE SHOULD KNOW
-
- the installation procedure
-
- the interactive user interface & the arguments passed on startup
-
- the various Angie Intuition actions
-
- the syntax of AngieSequences
-
- the arexx interface
-
- programming info, implementation details
-
- program history
-
- final notes
-
- contacting the author
-
- credits
-
- appendix: how to define a hotkey
-
- appendix: tutorial / the supplied hotkey mapping
-
-
-
- preface
- -------
-
- Angie is a nice name as well as a terrific song by the Rolling Stones.
- From now on, this name is to be remembered in the Amiga community as well:
- Angie, i.e. this software's name is an acronym for
-
- ANother Great Intuition Enhancer
-
-
-
- The Angie commodity is dedicated to all Amiga users that are tired of using
- the many utilities that use dirty hacks and don't care about offical CBM
- access protocols. Angie was written with the aim to provide you with a
- commodity that avoids illegal memory access and unsecured or undocumented
- access to global system shared data in all cases and by all means.
-
-
-
-
-
-
- concepts, program design
- ------------------------
-
- In fact, the Angie commodity enhances Amiga's unique Intuition
- graphical user interface in many ways. But what is even better: It
- is thoroughly customizable by the user - i.e. YOU; thus you have
- the ability to adapt it to your personal taste and likes in almost
- any way whatsoever. This is accomplished by providing you with
- complete user control of almost all of Angie's significant
- characteristics from within a nitfy graphical user interface (and
- save them for later retrieval from there, of course)
-
- Amongst Angie's capabilities there are automatic window hunting (i.e.
- active screen and active window to front, adjusting the display of
- over-sized autoscroll screens) as provided by Jörg Bublath's HuntWindow,
- retrieval of the last active window & the last active screen on hotkey,
- remembering & retrieval the last active window of all screens (similar to
- Tron's TWA), and a hitherto unique 'Key screen activation' feature that
- activates the last window remembered (or the window under the mouse, or the
- screen's frontmost window if none is remembered) of the screen under the
- mouse *if, and only if* the active window is not placed in one of the at
- least partially visible screens and a key downstroke event is rushing in
- from the input device. This feature has proved *very* ergonomic and nifty
- (in deed, it was actually the motivation for me to embark on this
- project;-)) Moreover, Angie can automatically raise the priority of the
- task that owns the currently active window (and restore it when the window
- becomes inactive, of course) However, the best is that Angie (don't you
- forget the triad: the nice name, the terrific Rolling Stones song and the
- neat commodity we are talking about...) provides you with the ability to
- map arbitrary 'AngieSequences' to any number of arbitrary trigger input
- events. 'AngieSequences' may consist of Angie's sixty Intuition actions,
- arbitrary async / sync dos commands, raw ascii text and commodities input
- descriptions with arbitrary delays between each of the elements. You may
- even choose whether the input event that triggers the respective operation
- shall be filtered or propagated to the other commodities objects. Starting
- from version 3.5, you can feed Angie with AngieSequences via its ARexx
- port, too.
-
-
- Angie can take advantage of several V39 Intuition / GadTools and V38
- Commodities features but operates well with V37 Intuition/ GadTools/
- Commodities, too.
-
-
-
-
- ATTN. lazy boys and girls - WHAT EVERYONE SHOULD KNOW
- -----------------------------------------------------
-
- EVERYONE should know that Angie is GIFTWARE - thus you shouldn't hesitate
- to send the author a gift, a small donation or AT LEAST a nice postcard if
- you use it.
-
-
- AS OF ANGIE 3.6 (the final version for 1993!), you can use the '¶'
- character (usually <alt p>) as a substitute for the linefeed character
- within dos_command_sequences.
-
- AS OF ANGIE 3.6 you can use the configuration that is stored in the
- 'PROGDIR:Angie' icon by not supplying any arguments if you start Angie from
- the shell
-
- AS OF ANGIE 3.5, Angie has an AREXX PORT named 'ANGIEREXX' that processes
- arbitrary AngieSequences you send to it.
-
- AS OF ANGIE 3.3, hotkey list browsing has been highly optimized - this is
- especially of interest for all poor 68000/68010 users as this action has
- turned out to be very sluggish in former Angie versions on their machines.
- Angie's GUI now works great even with the most excentric proportional
- fonts. In addition to this, AngieSequence execution backlogging is avoided
- and the user always gets an immediate feedback for GUI window inputs, no
- matter whether thousands of AngieSequences or auto hunts are waiting for
- execution.
-
- AS OF ANGIE 3.1, three very useful utilities for the use in AngieSequences
- are supplied: SetActiveWin, MagicPubName & RawInsert. All are written and
- copyrighted by the author of Angie. Have close look at their
- documentations for more details about them - have a VERY close look at
- the example AngieSequences in the documentation of SetActiveWin.
-
- AS OF ANGIE 3.1, SyncDosSequences are executed differently: NO CONSOLE is
- opened for them, and they run with the current task priority of Angie
- instead of the priority, Angie was started with.
-
-
-
- NEW FEATURES OF ANGIE 3.0:
-
- Angie 3.0 drops the restrictions of commodities.library V37-V40 in terms of
- parsing input descriptions: For V37, the rawmouse keycodes
- 'MOUSE_LEFTPRESS', 'MOUSE_MIDDLEPRESS' & 'MOUSE_RIGHTPRESS' that are
- usually only available in commodities.library V38 or higher are supported.
- As of V40, commodities.library doesn't support keycodes for the keyboard
- qualifiers. Angie allows you to use the rawkey keycodes 'CONTROL_PRESS',
- 'CAPS_PRESS', 'LSHIFT_PRESS', 'RSHIFT_PRESS', 'LALT_PRESS', 'RALT_PRESS',
- 'LAMIGA_PRESS' & 'RAMIGA_PRESS'. These parsing extensions are made in a
- highly compatible manner, of course - they are likely to work in all
- future versions of commodities.library.
- You should keep in mind that the inability of commodities.library V37 to
- apply the 'leftbutton', 'midbutton' & 'rbutton' qualifiers correctly is NOT
- affected by these internal enhancements of Angie.
-
- IT IS MOST IMPORTANT FOR USERS UPGRADING FROM FORMER VERSIONS OF ANGIE TO
- KNOW THAT AS OF ANGIE 3.0, YOU ASSIGN 'ANGIESEQUENCES' TO YOUR HOTKEYS. An
- 'AngieSequence' consists of ANY NUMBER of Angie's Intuition-related
- actions, arbitrary async or sync dos command sequences, raw ascii text
- sequences and commodities input descriptions, with arbitrary delays between
- each of the elements. Thus, programming Angie is now much easier than in
- former versions (In translator terminology, you would say 'Angie 2.0
- ENABLED Angie programming, whereas Angie 3.0 SUPPORTS Angie programming').
- In other words, as of Angie 3.0, you can VERY EASILY ASSIGN MULTIPLE
- VARIOUS ACTIONS TO ONE SINGLE HOTKEY. As a consequence of this
- trailblazing new concept, Angie 3.0 has now a different tooltypes format,
- whilst it is still capable of reading the old prefs format.
-
- Another new feature of Angie 3.0 is the new 'NoFilter' attribute which
- replaces the old 'ToFront' attribute (that may now be specified separately
- for each element of an 'AngieSequence'). It has the effect that the
- respective input event that triggers the execution of the appertaining
- AngieSequence is left in the input stream rather than filtering it, which
- is the default.
-
- Angie 3.0 has a new default auto hunt mode, called 'CapsLock1'. The old
- 'CapsLock' mode of Angie 2.0 is optionally still available as 'CapsLock2'.
-
- In the CapsLock* auto hunt modes, the CapsLock qualifier is alienated as a
- 'Hunt Always' toggle to change the mode on the fly. For the CapsLock2
- mode, all CapsLock events along with the CapsLock qualifier are filtered by
- Angie (so they don't affect neither the hotkeys you defined within Angie
- nor any other brokers that are linked into the commodities network after
- Angie's broker).
-
- UNTIL ANGIE 1.7, rawkey hotkeys inside and outside Angie that shuffled
- screens didn't work correctly in connection with an active Key Screen
- Activation feature if you neglected to specify the NoScrAct attribute for
- hotkeys inside Angie resp. if you neglected to define NoKeyActivate pseudo
- hotkeys for foreign hotkeys. Note that STARTING FROM ANGIE 2.0, this
- effect has vanished, as Angie now uses another, more complex -yet very
- compatible- method for its key screen activation action. Unfortunately,
- UNTIL ANGIE 3.2, the documentation still reflected the ANGIE 1.7 state.
-
-
-
- GENERAL ISSUES
-
-
- When does an auto hunt action happen????
- An auto hunt action does not necessarily take place immediately when
- a change is detected: If one or both of the left mouse button
- and its keyboard equivalent (lalt amiga) are pressed, this action is
- deferred until at least one of them is released. Furthermore, pressing
- the right mouse button or keeping it pressed does always cancel resp.
- inhibit any auto hunt action that is due. For the 'CapsLock*' auto hunt
- modes, the same goes for an active (illuminated) capslock key, too.
-
-
- You are advised to set the 'NoScrAct' attribute for all your rawkey hotkeys
- that shuffle screens and don't activate a window on the new frontmost
- screen and for your rawkey hotkeys that retrieve windows (i.e. hotkeys
- mapped to actions like 'NextScreen', 'PrevScreen', 'WBenchScreen',
- 'HuntWindow', 'LastActive' or 'LastActiveScr') This keeps the respective
- rawkey events from triggering a key screen activation action (such an
- action is usually undesirable in these cases).
-
- As for other commodities' / Intuition's rawkey hotkeys that perform such
- actions, key screen activation is usually undesirable, too, you can exclude
- those foreign hotkeys from triggering key screen activation action by
- defining NoKeyActivate pseudo hotkeys inside Angie for them. These
- NoKeyActivate pseudo hotkeys have the only effect that Angie doesn't
- trigger key screen activation action for the respective rawkey input
- events. E.g, you may exclude standard Intuition lcommand m/n screen
- shuffling from triggering a key screen activation action:
- 'lcommand -repeat -caps -alt -control m' &
- 'lcommand -repeat -caps -alt -control n' &
- 'lcommand lamiga_press'
- (pseudo action from menu: 'NoKeyActivate')
-
-
-
-
- The STRING GADGETS of Angie have SPECIAL EDITING FEATURES: 'ESC'
- cancels the editing operation, and for the 'Edit Hotkeys' & 'Action'
- gadgets, the CURSOR UP/DOWN KEYS have a special functionality.
-
- Pressing 'ESC' outside the string gadgets closes Angie's GUI window,
- pressing 'Z' zips the GUI window, and the cursor up/down keys can be used
- to browse through the hotkey list.
-
-
- All shell command line arguments that have values assigned need to be
- surrounded by quotes, e.g. "CX_PRIORITY=127" instead of just
- CX_PRIORITY=127.
-
-
- As of version 2.0, Angie's support for the 'active screen yet no active
- window present' case has greatly improved: Three of the consequences
- (there are many more):
- 1. The hotkey action 'HuntWindow' now hunts the active screen if no active
- window exists.
- 2. If key screen activation is selected
- and a (partially) visible screen is active along with no active window, a
- key screen activation action is issued (the preferred window for that
- specific action is the last active window of the active screen).
- 3. All hotkey actions based on windows cause a 'Key screen activation'
- action with a Hunt or WindowToFront() of the resulting window according to
- the hotkey's attributes if no active window exists.
-
-
-
- the installation procedure
- --------------------------
-
- The installation is done by the supplied 'InstallAngie' script.
-
-
-
- the interactive user interface & the arguments passed on startup
- ----------------------------------------------------------------
-
- The GUI conforms to Commodore's User Interface Style Guide, thus it should
- be mostly intuitive and self-explanatory to the User who is familiar with
- Commodore's commodities and preferences editors supplied with the operating
- system. The usual commodities arguments 'CX_PRIORITY, CX_POPUP & CX_POPKEY
- are supported.
-
- Notez-bien: If you start Angie from shell, all arguments that have values
- assigned need to be surrounded by quotes, e.g.
- "CX_PRIORITY=127" instead of just CX_PRIORITY=127
-
- You can use the configuration stored in the 'PROGDIR:Angie' icon if you
- specify the 'DEFAULTPREFS' argument or if you launch Angie from shell and
- don't specify any arguments at all.
-
-
- Following now is a brief description of the GUI elements and Angie's
- arguments:
-
-
- The 'Auto hunt mode' cycle gadget:
- With this cycle gadget you can control Angie's automatic hunt feature.
- This feature controls whether or not Angie shall automatically hunt,
- A Hunt action consists of popping the active window & the active screen
- to front & adapting the active screen's position so that as much of the
- active window as possible is visible. It is done in a way that minimum
- screen move takes place. In case the window is too large to fit in the
- actual display, the screen is moved so that the left/top edge of the
- window is displayed in the left/top edge of the visible portion of the
- screen - except for backdrop windows, where it is only ensured that the
- screen's display clip is completely filled with the screen's data (i.e.
- if the screen is dragged down, it will reposition, otherwise not).
- If the automatic hunt feature of Angie is active, a hunt operation is
- issued whenever the active screen or the active window or the active
- window's position or size have changed.
-
- An auto hunt action does not necessarily take place immediately when
- a change is detected: If one or both of the left mouse button
- and its keyboard equivalent (lalt amiga) are pressed, this action is
- deferred until at least one of them is released. Furthermore, pressing
- the right mouse button or keeping it pressed does always cancel resp.
- inhibit any auto hunt action that is due. For the 'CapsLock*' auto hunt
- modes, the same goes for an active (illuminated) CapsLock key, too.
-
- There are four different cycle states for this gadget:
- A: 'CapsLock1': In this mode, Angie's auto hunt is always considered
- to be on unless the CapsLock key is active (illuminated). The CapsLock
- key is alienated as a 'Hunt Always' toggle to change the mode on the
- fly. This mode is the default mode
- B: 'CapsLock2': same as 'CapsLock1'. Additionally, all CapsLock events
- and the CapsLock qualifier are swallowed by Angie and thus don't affect
- Angie's hotkey definitions nor any brokers that are linked into the
- commodities network after Angie's broker.
- C: 'Always': In this mode, auto hunt is always on - no special CapsLock
- magic takes place
- D: 'Off': This selection turns auto window hunting permanently off.
-
- The argument for this toggle is 'AUTOHUNTMODE', it defaults to
- 'CAPSLOCK1'
-
-
- The checkbox toggle gadgets:
-
- 'Hunt on wintofront hotkeys' - if enabled, Angie performs an automatic
- hunt (see above) operation whenever it issues a hotkey-bound
- Window_To_Front.
- The corresponding argument is 'HUNTMODEWFRONT' and defaults to 'YES'
-
- 'Hunt: set default public screen' - toggles the automatic declaration of
- the active window's screen as the system's default public screen
- whenever a hunt (see above) operation is done. If the active screen
- is no public screen, the Workbench screen is set as default public
- screen.
- The argument for this toggle is 'HUNTMODESETDEFPUBSCR' and defaults to
- 'NO'
-
- 'Key screen activation' - (de)activates a nifty, hitherto unique
- feature that activates the last active window of the screen under
- the mouse (or the window under the mouse, or the screen's frontmost
- window if none is remembered) *if, and only if* the active window
- is not placed in one of the at least partially visible screens and
- a key downstroke event rushes in from the input.device. This
- feature has proved very ergonomic and nifty, especially if
- immediate activation after screen shuffling is not appropriate
- (indeed, this feature was actually the motivation for me to
- embark on this project;-))
- 'KEYACTIVATE' is the argument for this, and defaults to 'YES'
-
- 'Raise Active WinTask's Pri' - determines whether Angie should always
- raise the priority of the task, the active window is associated with,
- by one, and restore the old priority on deactivation if the priority
- hasn't been changed by someone else in the meantime.
- The correct argument is 'RAISEWINTASKPRI', default is 'YES'
-
- 'Shuffle backdrop windows' - decides whether backdrop windows should be
- considered when performing AngieSequence-bound window-shuffling or not.
- The default is 'NO', the argument is named 'SHUFFLEBACKDROP'.
-
- 'Pop GUI on startup' - if you want Angie's GUI window to pop open when
- Angie is launched, set this toggle, otherwise switch it off.
- The appertaining argument is 'CX_POPUP' and defaults to 'YES'.
-
-
- The sliders have the following significance:
-
- 'Stable time' - this one is used to adjust the time in milliseconds, the
- snoop task expects the active window, the active screen, the active
- window's size and its position to remain unchanged until it signals a
- change to the main task. The valid range is -1 up to 1000, where -1 is
- a magic value that signifies that whenever the snoop task detects
- a change, it immediately signals the main task. All positive values
- including 0 require the snapshot data to remain unchanged for at
- least two snoops and a minimum of 'Stable time' milliseconds before
- the main task is signalled.
- The argument for this characteristic is called 'STABLETIME' and defaults
- to 20.
-
- 'Snoop delay' - this is the delay time in milliseconds, the SnoopTask
- should wait between two snoops. The valid range is 10..1000. Note that
- the accuracy of this delay is bound to the frequency of the vertical
- blanking interrupt, which is usually 50Hz PAL, 60Hz NTSC, 70Hz
- EURO36/EURO72/SUPER72, that means, you'll never get more than 50 snoops
- per second for PAL, never more than 60 snoops per second for NTSC and
- never more than 70 snoops per second for EURO36/EURO72/SUPER72.
- Note that allocating a CIA timer for this job to gain accuracy would
- be IMHO a waste of system resources. Huge values for this characteristic
- yearn for a '-1' 'Stable time' setting.
- The argument name for this value is 'SNOOPDELAY' and defaults to 30.
-
- 'Screen steps' - use this slider to set the quantity a screen should be
- moved with the 'MoveScrXXX' hotkey actions. The quantity is provided
- as the 'Screen steps'-th part of the display clip of the active screen.
- The range for this quantity is 1..50
- This argument defaults to '5', its name is 'SCRMOVESTEPS'
-
- 'Window steps' - this is the same as above except that this value is
- applied for window moving and dimensioning via the 'MoveXXX',
- 'ExpandXXX' and 'ShrinkXXX' hotkey actions. The range is 1..50,
- too.
- The corresponding argument is named 'WINMOVESTEPS' and defaults to 5
-
- 'CX priority' - use this to set Angie's commodity broker's priority.
- Note well that this action takes effect immediately - the effort to
- achieve this in a documented way was quite high, by the way.
- The argument for this is called 'CX_PRIORITY' and defaults to 0
-
-
- There's one separate text entry gadget, named 'Window shuffle pattern'
- where you can enter the pattern to be applied to windows' names when
- doing a window shuffle ('ActivateNext' / 'ActivatePrev') hotkey action.
- Windows whose titles don't match to the pattern are skipped.
- The argument name for this setting is 'SHUFFLEPAT' and defaults to '#?'
- (which matches all names, incl. an empty name)
-
-
- The other gadgets form a system to maintain the action hotkey list of
- Angie:
-
- Use the 'ADD' gadget to add new hotkeys to the list, the 'DEL' gadget to
- delete hotkeys from the list, the 'UP' gadget to move an entry up in the
- list, the 'DOWN' gadget to move an entry down in the list, use the
- listview to browse through the hotkey list and to select the active
- hotkey, the change operations will affect.
-
-
- The 'Action' text entry gadget is one of these change operation gadgets:
- You can enter an arbitrary 'AngieSequence' with up to 255 characters in
- this gadget that is to be executed when the hotkey is triggered. Plain
- text outside brackets is considered as ascii text that is to be inserted
- into the input stream, text in angled brackets like '<lshift lshift_press>'
- represents a commodities input description, text in normal brackets like
- '(^ActivateNextScreen)' represents an Angie Intuition related action (or if
- it doesn't match an Angie Intuition action it is considered to be an async
- dos command sequence), text in '[]' brackets like
- '[^cd ram:<CTRL-J>newshell *]' represents a dos command sequence that shall
- be launched asynchronously, whereas text in '{}' brackets like
- {magicpubname q tofront CygnusEdScreen1} represents a dos command sequence
- that shall be executed synchronously. '#n' specifies the delay to wait
- between processing two elements of an AngieSequence / inserting each char
- of plain text and '~n' stands for a one-time delay (the valid range for n
- is 0..999 milliseconds). As the very first character of the AngieSequence
- or as the character following immediately after the opening bracket in case
- of '()'/'[]'/'{}'- bracketed elements, a '^' - ToFront attribute may be
- specified. It has the effect, that either the window involved in the
- operation, or if no window but a screen is involved, the involved screen,
- is popped to the front. To give you a rough idea about AngieSequences, e.g.
- '{magicpubname q tofront ShellScr}(^ActivateFrontScr)<control x>~200 list '
- is a valid AngieSequence.
-
- Within the 'Action' gadget, the cursor up/down keys have some special
- functionality. If the cursor is within a bracketed element, or on a
- space character, these cursor key presses have the effect that this element
- is replaced by either the first or last action of the actions in Angie's
- Angie Intuition action list. Otherwise, if the cursor is not within a
- bracketed element or over a space character, the respective Angie Intuition
- action is inserted at the cursor position. Any following, consecutive cursor
- up/down presses simply shuffle through Angie's Intuition action list.
- Pressing ESCape quits the gadget by discarding all changes that have been made.
-
- An additional way of modifying the contents of the 'Action' gadget is
- selecting the respective Angie Intuition action in the 'Edit·Hotkey·Type'
- menu. This replaces the WHOLE contents of the action gadget with the
- selected action.
-
-
-
- Another change operation is the selection of the 'Attrs' gadget. You can
- assign three different attributes to the hotkey entry with this gadget:
-
- 1. 'NoFilter': If this attribute is enabled, an input event that matches
- the hotkey is propagated to the other commodities objects rather than being
- filtered which is the default.
-
- 2. 'NoScrAct': This attribute inhibits a rawkey hotkey from triggering an
- automatic 'Key screen activation' action (see above). This attribute is
- enforced for the 'NoKeyActivate' pseudo action. It should be generally
- used for hotkeys with actions that shuffle screens without activating a
- window on the new frontmost screen or for hotkeys with actions that hunt or
- retrieve windows like 'HuntWindow', 'LastActive' or 'LastActiveScr'.
-
- 3. 'Repeatbl': This attribute signifies that matching rawkey events
- with the 'repeat' qualifier set shall be normally processed rather than
- just being filtered, which is the default. It is of no use at all to
- apply this attribute to a hotkey that has both, no '-repeat'
- maybe-qualifier and no 'repeat' qualifier set in its definition.
-
-
- Furthermore, you can toggle the different attributes by using the
- 'Edit·Hotkey·Type->Attributes' submenu toggle items.
-
-
-
- However, the most important change operation gadget is the listview's
- string gadget where you can modify the commodities input description for
- the hotkey. If you enter an invalid input description, the former
- description is reused instead of the one you entered. Note that you can
- leave the string gadget by pressing cursor up/down, too: The cursor
- up/down keys are equivalent to pressing return within the string gadget and
- right afterwards pressing cursor up/down. As all other Angie string
- gadgets, this string gadget can be quit by pressing ESC, which has the
- effect that the gadget's contents are discarded and the gadget is
- refreshed.
-
-
- The Project menu is intuitive:
-
- -New resets Angie to the default configuration
-
- -Read·Settings reads the configuration that are currently stored in the
- PROGDIR:Angie icon.
-
- -Restore·Settings restores the settings to the latest arguments that
- were read either at startup or after selecting the Read·Settings menu
- item.
-
- -Save·Settings saves the current configuration into the PROGDIR:Angie
- icon
-
- -About brings up a requester with information about Angie. Note that
- while the About requester is displayed, Angie is in inactive state.
-
- -Hide closes the GUI window
-
- -Quit causes Angie to shut completely down
-
-
-
- The underscored character of a gadget's text signifies the key shortcut for
- selecting the respective gadget, additionally the cursor up / down keys are
- used to scroll through the hotkeys in the listview, the DEL key is used to
- delete the current entry in the listview, the ESCape key or the close
- gadget is used to close Angie's GUI window, and the 'Z' key or the Zoom
- gadget is used to (un-)iconify the GUI window.
-
- There exists one common non-standard editing feature of all of Angie's
- text entry gadgets: Pressing 'ESC' leaves the gadget by discarding
- all changes made to it, i.e. a sort of 'CANCEL' operation.
-
-
-
- the various Angie Intuition actions
- -----------------------------------
-
-
- Now, let's discuss the various Angie Intuition actions:
-
-
- CX_POPKEY:
- Pop Angie's GUI window open, activate and hunt it if it is already open.
-
- HuntWindow:
- Perform a hunt action (see above) right now.
-
- Activate:
- Activate the window under the mouse
-
- ActivateNext:
- Shuffle forward through the current active screen's window list
-
- ActivatePrev:
- Shuffle backward through the current active screen's window list
-
- ActivateBackdrop:
- Activate the active screen's first backdrop window
-
- ActivateFrontScr:
- Activate the frontmost window on the frontmost screen.
-
- LastActive:
- Activate the window that was active right before the current active
- window if it still exists, In case it doesn't exist any more, but
- it was opened on another screen that still exists, this action
- activates that screen's frontmost window.
-
- LastActiveScreen:
- Activate the last active window of the last active screen, if it still
- exists. If it doesn't exist anymore, but the screen on which it was open
- still exists, then activate the frontmost window on that screen.
-
- ToFront:
- Pops the currently active window to front
-
- ToBack:
- Moves the currently active window to the back
-
- AdaptWindow:
- This is something like an 'inverted hunt' action: the active window is
- (if necessary) moved and shrunk in a way that it fits into the currently
- displayed portion of its screen.
-
- CenterWindow:
- The active window is centered within the currently displayed portion of
- its screen.
-
- Zip:
- The active window is zipped (equivalent to selecting the Zoom gadget)
-
- Close:
- A selection of the active window's close gadget is emulated
-
- Max:
- The active window's position and size are changed to exactly fill the
- screen's visible portion.
-
- MaxWidth:
- The same as for above, but only horizontally, and if at least a part of
- the window would be visible in the screens display portion with
- consideration to the vertical window position & dimension.
-
- MaxHeight:
- Like MaxWidth, but now vertically.
-
- MinWin:
- The active window is shrunk to its minimum dimensions and moved into the
- lower right edge of the screen's visible portion
-
- MoveLeft / MoveRight / MoveUp / MoveDown:
- Move the active window in the respective direction, the move quantity is
- derived from the 'Window steps' setting.
-
- UpperLeft / LowerLeft / UpperRight / LowerRight:
- Place the active window in the respective edge of the screen's visible
- portion
-
- ExpandWidth / ExpandHeight / ShrinkWidth / ShrinkHeight:
- Expand / shrink the active window's width / height. The quantity
- to expand /shrink is derived from the 'Window steps' setting.
-
- DoubleWidth / DoubleHeight / HalveWidth / HalveHeight:
- Double / halve the active window's width / height
-
- ActivateNextScreen / ActivatePrevScreen / ActivateWBenchScreen /
- ActivateDefPubScreen:
- Shuffles the screen list forward / backward, resp. pops the Workbench
- screen / default public screen to the front and activates the last
- active window of the new front screen or the frontmost window of the
- screen instead. If the 'Hunt: set default public screen' toggle is
- set and either the 'Hunt always' toggle is set, or both, the 'Hunt on
- wintofront hotkeys' toggle is set and the 'window to front' attribute
- is set for the hotkey, it will also make the new front screen the
- default public screen even if no windows are open on it.
-
- NextScreen / PrevScreen / WBenchScreen / DefPubScreen:
- the same as for the corresponding ActivateXXXXScreen entries except
- that no window activation and no default public screen definition
- magic takes place.
-
- ScrollScrLeft / ScrollScrRight / ScrollScrUp / ScrollScrDown:
- scrolls the active screen in the respective direction. The scroll
- quantity is derived from the 'Screen steps' setting.
-
- UpperLeftScr / LowerLeftScr / UpperRightScr / LowerRightScr /
- ShowScrCenter:
- makes the respective portion of the active screen visible in its
- display clip.
-
- ScreenTop:
- aligns the top edge of the active screen with the top edge of its
- display clip
-
- SetDefPubScreen:
- makes the active screen the default public screen. If the frontmost
- screen is a screen with no windows open, and the active screen is
- completely invisible, the frontmost screen is used instead for this
- operation. If the screen is not a public screen, the Workbench screen
- is set as the new default public screen.
-
- Filter: (** pseudo action - select this through the menu!! **)
- This is a real nop operation: It does nothing at all. Thus, the
- only job of this action is to filter the respective hotkey input
- events out of the input stream.
-
- NoKeyActivate: (** pseudo action - select this through the menu!! **)
- All (rawkey) input events matching this hotkey's input description are
- excluded from triggering 'Key screen activation' (see above). This is
- useful to keep other commodities' / input handlers' rawkey hotkeys from
- triggering key screen activation action. You may want that for foreign
- rawkey hotkeys that shuffle screens and don't activate a window on the
- new frontmost screen (like Intuition lcommand m/n).
-
-
-
- the syntax of AngieSequences
- -----------------------------
-
- In the following definition, terms surrounded by '[]' brackets may be
- omitted. The same goes for terms surrounded by '{}' brackets, except that
- these terms may be even repeated any times you want.
-
- AngieSequence := [ ToFrontAttr ] AngieSequence1
-
- AngieSequence1 := { IntuitionSequence | AsyncDosSequence | SyncDosSequence |
- CxInputSequence | AsciiChar | DelaySequence |
- OneDelaySequence }
-
- IntuitionSequence := '(' [ ToFrontAttr ] Angie_Intuition_action_string ')'
-
- Angie_Intuition_action_string := Angie_Intuition_action |
- async_dos_command_sequence
-
- Angie_Intuition_action := "any of Angie's valid Intuition action names as
- displayed in the Edit·Hotkey·Type menu,
- except a pseudo_action_name"
-
- pseudo_action_name := 'Filter' | 'NoKeyActivate' | 'Custom'
-
- AsyncDosSequence := '[' [ ToFrontAttr ] async_dos_command_sequence ']'
-
- SyncDosSequence := '{' [ ToFrontAttr ] sync_dos_command_sequence '}'
-
- async_dos_command_sequence := dos_command_sequence
-
- sync_dos_command_sequence := dos_command_sequence
-
- dos_command_sequence := [ linefeed | dos_command_line ]
- [ linefeed dos_command_sequence ]
-
- linefeed := '<control-j>' | '¶' ; '¶' = <alt p>
-
- dos_command_line := "a line of ascii text that is executed
- as a dos command line"
-
- CxInputSequence := '<' input_description '>'
-
- input_description := "a description string for an input event
- respectively for an IX according to
- commodities.library."
-
- AsciiChar := esc_sequence | valid_ascii ; short circuit evaluation here!
-
- esc_sequence := '\' esc_desc
-
- esc_desc := [ 'n' | 'r' | '0' | 't' | 'f' | ''' | '"' |
- '<' | '(' | '[' | '{' | '\' | 'x' hex_value ]
-
- valid_ascii := "any ASCII characters except an invalid_ascii character"
-
- invalid_ascii := '<' | '(' | '[' | '{'
-
- hex_value := hex_nibble [ hex_nibble ]
-
- hex_nibble := '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' |
- '9' | '0' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
-
- DelaySequence := '#' [delay_value] [ ' ' ]
-
- OneDelaySequence := '~' [delay_value] [ ' ' ]
-
- delay_value := "decimal digits representation of time in milliseconds to
- delay, range 0..999"
-
- ToFrontAttr := '^';
-
- NOTE:
- -Whereever the ToFrontAttr may be specified, and a '\^' sequence
- follows immediately after that position, the '\^' sequence is replaced
- by a simple '^' character.
-
- -Moreover, inside bracketed AngieSequence1
- elements, the closing bracket may be specified as a normal character of
- that element by prepending a '\' to the closing bracket.
- e.g. '[echo "[Hello\]"]' is a valid async_dos_command_sequence
-
-
-
- Most of the formal stuff should be self-explanatory. However, some things
- deserve a verbose discussion:
-
- The dalay_value of DelaySequence & OneDelaySequence defaults to 50 if it
- is not specified.
-
- The effects of the ToFrontAttr element:
-
- -as the first element of the AngieSequence, it originates a 'ToFront'
- Angie_Intuition_action before the rest of the AngieSequence is processed.
-
- -for dos_command_sequences, it causes the default public screen to be popped
- to the front before the dos_command_sequence is launched
-
- -for Angie_Intuition_actions, its effect depends on the action itself: if a
- window is affected by the action, that window is popped to the front.
- Otherwise, if no window at all, but a screen is involved in the action,
- that screen is popped to the front. BTW: For the 'ToBack' action, it has
- no effect at all, of course;-)
-
-
- The esc_sequence character translation:
-
- \n - linefeed (inserted as carriage return)
- \r - carriage return
- \0 - nul
- \t - horizontal tab
- \f - formfeed
- \xff - ASCII code 0xff (f represents an arbitrary hex nibble)
- \' - apostrophe
- \" - quotation mark
- \\ - backslash '\'
- \< - '<' opening bracket
- \( - '(' opening bracket
- \[ - '[' opening bracket
- \{ - '{' opening bracket
-
-
-
- NOTEZ-BIEN!!!
- sync_dos_command_sequences are rather dangerous since during their
- execution Angie is BLOCKED for any other action. So please only use
- sync_dos_command_sequences in AngieSequences like
- '{magicpubname q tofront CygnusEdScreen1}(^ActivateFrontScr)' where the
- dos_command_sequence really has to be executed synchronously, and
- where its execution doesn't take much time. NEVER launch interactive
- applications / tools or similar things synchronously!!!
-
-
- The launching parameters for async_dos_command_sequence execution:
- The priority of the launched task will
- be the same as the priority, Angie was started with - the same goes for
- the stack size, current directory and the dos command search path.
- Input and Output are set to an interactive console window with the
- WAIT/AUTO/CLOSE attributes, its position and alternative ('zoom')
- position are optimized for the currently displayed portion of the default
- public screen. The console will open on the default public screen at
- the very moment when the first input/output operation takes place.
-
- For sync_dos_command_sequence execution, the only two differences are that
- no console is opened for them, and they run with the current task priority
- of Angie.
-
-
- the arexx interface
- -------------------
-
- Angie offers an Arexx interface in order to provide you with the ability to
- make Angie execute arbitrary AngieSequences from ARexx scripts or any other
- source. For this purpose, Angie maintains a public Arexx port named
- 'ANGIEREXX'.
-
- A simple example for an ARexx script:
-
- options results
- address command 'SetActiveWin tpat (%|#?/|#:)Clock'
- if rc = 0 then address 'ANGIEREXX' '(HuntWindow)'
- else address command 'run <nil: <nil: sys:utilities/clock'
-
- Apart from that, you can quit Angie by sending the 'QUIT' command to
- Angie's ARexx port.
-
-
-
- programming info, implementation details
- ----------------------------------------
-
- Angie is completely written in Amiga-Oberon, a superset of a powerful
- object-oriented language by Nicolaus Wirth, that offers all the flexibility
- and excellent code generation that is needed for Amiga system and
- application programming. I tried hard to make Angie conforming with the
- User Interface Style Guide, and to make it really free of bugs. I can tell
- you that despite having used Oberon runtime checking code (which is
- disabled in this official release), Enforcer and Mungwall, this release has
- been proved free of any bugs (however, don't blame me if you find one
- though: you know Murphy rules...;-^) Especially, I always tried to ensure
- that all accesses to system data are protected by the respective official
- CBM protocols. Since within interrupts there is no such protocol for
- Intuition data structures available, I placed the snooping code for window
- hunting, raising of the active window task's priority, remembering of the
- last window and all the last windows of a screen, in a child task rather
- than within interrupt code.
-
- If you find any bugs or you have any suggestions for improving Angie or
- extending its functionality, or if you just want its source code,
- you are encouraged to contact the author via electronic mail (preferred)
- or snail mail.
-
-
- If you own a 68000 you may wonder why Angie's snoop task uses quite more
- CPU time than you thought it uses (Note however that only Xoper2.4 gives
- you reliable information. Former versions of Xoper display much too much
- CPU time usage of tasks that are both, frequently switched and don't hold
- the CPU for a long time). Well, the solution is as follows: I decided to
- make Angie as system-friendly as possible. Angie has to snoop not only the
- IntuitionBase->ActiveWindow, but also elements like
- TopEdge/LeftEdge/Width/Height/WScreen of the ActiveWindow itself. In a
- consistent way, this is only possible within tasks, not interrupts, in
- conjunction with the (Un)LockIBase() protocol. However, task switching,
- the timer request for delaying, and especially the (Un)LockIBase() protocol
- produce an enormous overhead of CPU usage: I measured (on a 68030, OS3.0)
- that the snoop code itself only consumes 15% (fifteen) percent of the snoop
- task's total CPU usage (total CPU usage is less than 1% @ 30 ms snoopdelay
- on 68030, 25Mhz, OS3.0). With the snoop code removed, only the timer IO
- and (Un)LockIBase() stub left, the CPU usage of the snoop task was still at
- 85% of the original CPU usage. With (Un)LockIBase() removed, the snoop
- task's CPU usage was at about 45% of the original CPU usage.
-
-
-
-
-
- program history
- ---------------
-
-
- v1.0 20.10.93 [fSchwarz]
-
- v1.1 22.10.93 [fSchwarz] improved setDefPubScreen action
- fixed ActivateXXXXScreen; fixed Menu Attrs selection
-
- v1.2 23.10.93 [fSchwarz] doesn't send any closeWindow
- event on Close action when window is blocked by
- requesters.
-
- v1.3 24.10.93 [fSchwarz] added Edithook for hotkey
- definition gadget
-
- v1.4a 29.10.93 [fSchwarz] major code cleanup; now
- supports dos command and inputevent insertion type
-
- v1.5 4.11.93 [fSchwarz] now really uses the frontmost
- window of screens instead of just screen.firstWindow;
- improved Key Screen Activation handling for screens
- without windows
-
- v1.6 4.11.93 [fSchwarz] removed last Intuition stuff from
- cxcustom inputhandler - now all accesses to Intuition
- structures are safeguarded by official CBM protocols;
- enhanced Intuition/GadTools V37 GUI
-
- v1.7 7.11.93 [fSchwarz] now accounts the fact that
- ViewPortExtra.displayClip is volatile and dependent on
- the displayids of both, the affected screen & the front
- screen; improved timing in msghandler (results in faster
- Auto-Hunts when receiving many CxMsgs consecutively
- and in better hotkey recursion capabilities); now
- needs BlackMagic 1.14; fixed nasty Enforcer hit in
- DefinitionProc() that turned out very rarely and was
- due to use of post-freed memory (which was usually
- immediately reallocated, so Enforcer/Mungwall hardly
- ever noticed it); improved Intuition left mouse button
- effective detection
-
- v2.0 11.11.93 [fSchwarz] Angie is now completely localized;
- fixed rare timing problems that were due to rearranging
- Intuition related KeyScreenActivation stuff from the
- the cxcustom handler to the main task; changed again
- KeyScreenActivation handling; complete code heavily
- revised & updated to ensure optimal ergonomics when
- there's no current active window, yet an active screen;
- now right mouse button blocks all Auto-Hunt (it doesn't
- block hotkey-(attribute)-based hunts, though!);
- former WinToFront attribute changed to 'ToFront': *If
- and only if* the hotkey action doesn't involve a window,
- but a screen, the attribute causes a ScreenToFront()
- instead of a simple WindowToFront(). HuntWindow action
- now hunts the active screen if no active window exists;
- the KeyScreenActivation considers that case, too.
- Most window-related hotkey-actions (except Hunt) now
- simply activate the BestWindow() if there exists no
- active window (ToFront/Hunt according to the hotkey
- attrs); optimized LastActive-Action (now activates the
- frontmost window of the last window's screen if the
- last window doesn't exist any more, but the screen it
- was opened on, and that screen differs from the active
- one). Added Capslock-AutoHunt-mode (default!): capslock
- is alienated as an inverse Auto-Hunt toggle switch, all
- capslock events & capslock qualifier in inputevents
- are eliminated.; Now cxcustom handler code runs at
- three different priorities. Moved some IntuitionBase
- related window code to own module. Angie's minimum
- taskpri is now 5; wintask priority increment only
- happens if resulting priority isn't greater than
- Angie's taskpri. Added 'New', 'Read Settings' &
- 'Restore settings' to the project menu; remembers also
- the second last window/screen for LastActive/
- LastActiveScr actions; general changes in the code to
- obtain better ergonomics in many places; added
- 'DEFAULTPREFS' argument (especially for CLI): loads
- the configuration stored in PROGDIR:Angie.info.
- Angie now requires CxLib V1.1 with ArgArrayDiskObj().
- All tooltypes longer than 128 chars (the official
- length limit as of the RKMs) are now split by Angie
- for the icon writing (fixes problems with Workbench's
- Icon->Information menu item that prunes all longer
- tooltypes). Main module is now split into three modules.
- Plus several changes I forgot to mention here.
-
- v3.0 19.11.93 [fSchwarz] COMPLETELY NEW CONCEPT: Angie-
- Sequences, consisting of multiple Angie actions, ascii
- text, commodities input descriptions, & async / sync
- dos command sequences are now assigned to the hotkeys.
- The ToFront attribute is now replaced by a 'NoFilter'
- attribute (the ToFront attribute may now be specified
- separately for each item of an AngieSequence). Angie
- parses now qualifier keystrokes like 'LALT_PRESS' in
- input descriptions - along with mouse button keystrokes
- in input descriptions even for V37 commodities users;
- simple NoScrActivate pseudo hotkeys now work for V37,
- too (own ParseIX() extension, own V37 MatchIX()).
- fixed NewMenu array size of the edit menu. For
- proportional fonts, gimmeZeroZero windows are used in
- conjunction with other slLevelFormat - this fixes V37
- level display problems and keeps the window borders
- from messing up in those rare cases where the nominal
- proportional font's width is utterly misleading.
- Invocation of WindowToFront() is now omitted if the
- respective window is already the screen's frontmost
- window (results in much better performance for
- gimmeZeroZero windows). GetBestWin() now accounts that
- visible screens may follow after invisible screens in
- the IntuitionBase screen list. cx_pri slider step is
- now level-adaptive (like snoopdelay/stabletime sliders)
- A new tooltype format for hotkeys is now used - old
- format can still be read. Another new (default!)
- auto hunt mode is provided: CapsLock1 (functionality
- is the same as for the old CapsLock mode which is now
- called CapsLock2, except that capslock keystrokes & the
- capslock qualifier in the ievents are left untouched).
-
- v3.1 22.11.93 [fSchwarz] removed all code where
- LockLayerInfo() is called directly or indirectly with
- a locked IntuitionBase due to very unlikely deadlock
- situations that may arise from LockLayerInfo() when
- IBase is locked. Other protocol to avoid illegal
- mem access & to ensure valid window pointer is used
- instead. Distribution now includes my SetActiveWin
- and MagicPubName shell utilities that can be perfectly
- used in SyncDosSequences. In order to disencourage
- you from abusing SyncDosSequences for launching
- interactive stuff, etc, and in order to improve
- performance, SyncDosSequences are now executed without
- new I/O channels & with the same priority Angie is
- running. Fixed bug that kept Angie from activating
- the BestWindow for most Intuition actions in case
- no active window exists (bug was due to the severe
- code changes that were necessary for inventing the
- AngieSequence concept)
-
- v3.2 23.11.93 [fSchwarz] all CxMsgs of cxmIEvent type
- that are older than 2.5 seconds are discarded by the
- msghandler now; rearranged msghandler code - this
- fixes all backlog problems and makes the GUI accessable
- even when Angie is busy with CxMsgs & AutoHunt. Support
- for proportional fonts has now greatly improved: all
- strings in Angie's window are now accounted for
- calculating the window width - even for the most
- excentric proportional fonts, display won't mess up.
- The distribution now includes full-featured German
- docs, another utility (RawInsert) for DosSequences
- and SetActiveWin 1.1 (V1.0 could cause Intuition
- deadlocks!)
-
-
- v3.3 24.11.93 [fSchwarz] Strangely, AddIEvents() doesn't
- set the timeStamp of the InputEvents as opposed to
- the v37 input device writeEvent command - this caused
- problems in conjunction with the anti backlog handling
- that was invented in Angie 3.2, so Angie itself now
- sets the TimeStamp. The same problem was present in the
- RawInsert utility - now fixed in RawInsert 1.1;
- improved performance & minimized gadget/menu refresh
- for hotkey list browsing.
-
- v3.3a 25.11.93 [fSchwarz] fixed another small bug that
- was due to the code changes for the AngieSequence
- concept (scrActivateMagic const had to be set to a
- unique value outside the range of AngieSequence ids)
-
- v3.5 1.12.93 [fSchwarz] added AREXX interface for
- executing AngieSequences from outside Angie. Fixed
- bug in the SetActiveWin utility that frustrated
- activation of windows on non-public screens (V1.2)
-
- v3.6 3.12.93 [fSchwarz] adapted to Amiga-Oberon 3.10,
- fixed active/inactive state handling (now arexx works
- great even if Angie is in inactive state); fixed error
- exit code; introduced '¶'-lineFeedMagic as a linefeed
- substitute within dos_command_sequences.
- !!! THIS IS the last revision for 1993 !!!
-
-
-
- final notes
- -----------
-
- Known Bugs: Currently, no known bugs exist. However, due to the extent of
- this project, it is possible that a few bugs are in the code that haven't
- turned out yet.
-
-
- Angie is GIFTWARE. In other words THOU SHALT send the author a nice
- present, cash, or AT LEAST a postcard, if you use it.
-
- Suggestions, comments, bug reports, criticism, praise, etc. are welcomed,
- too!
-
- If you want to translate this documentation into other languages, feel free
- to do so, add the translation to this archive, and send it to the author
- (that is me;-)) The same goes for catalog translation files and catalogs.
-
-
- Angie is copyrighted and protected by copyright laws all over the world.
- Copyright © 1993 Franz Schwarz.
-
-
- The author can't be hold liable for any harm that stems from the
- usage of this program, no matter whether direct harm or indirect harm.
-
- Angie is freely distributable; it may be published in the Fred Fish
- & Amok software collections and in other non-commercial software
- collections, including CD-ROM versions of them. Moreover, it may be
- spread via electronic data transfer.
-
- Angie may only be distributed in this archive as a whole. The only
- exception from this: if this archive contains the source code of Angie,
- you may distribute a modified archive where _ONLY_ the complete 'txt' &
- 'Locale' drawers with the respective icons may be removed.
-
- Angie may be only distributed if the distributor does not claim any
- copyright on the Angie archive nor on any files that are compulsorily
- distributed with it (i.e. the distributor claims that this archive may not
- be distributed separately without those files). Inquiries on exceptions
- from these limitations may be submitted to the author.
-
-
- contacting the author
- ---------------------
-
- Franz Schwarz
- Mühlenstraße 2
- D-78591 Durchhausen, Germany
- Uucp: Franz_Schwarz@mil.ka.sub.org
- Fido Classic: 2:2476/506.18
- Bank account 951.207 at
- KSK Trossingen, Germany, bank ZIP code 643 500 70
-
-
-
-
- Credits
- -------
-
- The interactive graphical user interface was created with assistance of
- GadToolsBox 37.300 by Jan van der Baard and its Oberon source generator
- OG 38.02 by Stefan Kurtz, Thomas Igracki & Kai Bolay.
-
-
-
-
- Have fun, and don't you forget:
-
- Angie is a nice name as well as a terrific song by the Rolling Stones.
- From now on, this name is to be remembered in the Amiga community as well:
- Angie, i.e. this software's name is an acronym for
-
- ANother Great Intuition Enhancer
-
-
- Franz 'Blacky' Schwarz
-
- - Girlfriend Is Better - Talking Heads -
-
-
-
-
- appendix: how to define a hotkey
- --------------------------------
-
- Angie 3.0 drops the restrictions of commodities.library V37-V40 in terms of
- parsing input descriptions: For V37, the rawmouse keycodes
- 'MOUSE_LEFTPRESS', 'MOUSE_MIDDLEPRESS' & 'MOUSE_RIGHTPRESS' that are
- usually only available in commodities.library V38 or higher are supported.
- As of V40, commodities.library doesn't support keycodes for the keyboard
- qualifiers. Angie allows you to use the rawkey keycodes 'CONTROL_PRESS',
- 'CAPS_PRESS', 'LSHIFT_PRESS', 'RSHIFT_PRESS', 'LALT_PRESS', 'RALT_PRESS',
- 'LAMIGA_PRESS' & 'RAMIGA_PRESS'. These parsing extensions are made in a
- highly compatible manner, of course - they will very probably work in all
- future versions of commodities.library.
-
- Within Angie, valid input description strings are for ALL VERSIONS OF
- commodities.library:
- 'rawmouse leftbutton mouse_leftpress'
- 'rawmouse -capslock upstroke mouse_middlepress'
- 'lshift -capslock -control -alt lshift_press'
- '-capslock -upstroke caps_press'
- etc.
-
- THESE facts are NOT ACCOUNTED in the following text!!
-
- The following text is courtesy Stefan Becker and describes the structure of
- the currently defined commodities input descriptions:
-
- How to define a Hot Key
- ************************
-
- This chapter describes how to define a Hot Key as an Input
- Description String, which is then parsed by Commodities. Each time a
- Hot Key is activated Commodities generates an event which is used by
- ToolManager to activate Exec objects or to toggle Dock objects. A
- description string has the following syntax:
-
- [<class>] {[-][<qualifier>]} [-][upstroke] [<key code>]
-
- All keywords are case insensitive.
-
- `class' describes the InputEvent class. This parameter is optional
- and if it is missing the default `rawkey' is used. See InputEvent
- classes.
-
- Qualifiers are "signals" that must be set or cleared by the time the
- Hot Key is activated; otherwise no event will be generated. For each
- qualifier that must be set you supply its keyword. All other qualifiers
- are expected to be cleared by default. If you want to ignore a
- qualifier, just set a `-' before its keyword. See Qualifiers.
-
- Normally a Hot Key event is generated when a key is pressed. If the
- event should be generated when the key is released, supply the keyword
- `upstroke'. When both press and release of the key should generate an
- event, use `-upstroke'.
-
- The key code is depending on the InputEvent class. See Key codes.
-
- Note: Choose your hot keys *carefully*, because Commodities has a
- high priority in the InputEvent handler chain (i.e. will override
- existing definitions).
-
-
- InputEvent classes
- ===================
-
- Commodities supports most of the InputEvent classes that are
- generated by the input.device. This section describes those classes
- that are most useful for ToolManager Hot Keys.
-
- `rawkey'
- This is the default class and covers all keyboard events. For
- example `rawkey a' or `a' creates an event every time when the key
- "a" is pressed. You must specify a key code for this class. See
- rawkey key codes.
-
- `rawmouse'
- This class describes all mouse button events. You must specify a
- key code for this class. See rawmouse key codes.
-
- `diskinserted'
- Events of this class are generated when a disk is inserted in a
- drive. This class has no key codes.
-
- `diskremoved'
- Events of this class are generated when a disk is removed from a
- drive. This class has no key codes.
-
-
- Qualifiers
- ===========
-
- Some keyword synonyms were added to Commodities V38. These are
- marked with an `*'.
-
- `lshift', `left_shift' *
- Left shift key.
-
- `rshift', `right_shift' *
- Right shift key.
-
- `shift'
- Either shift key.
-
- `capslock', `caps_lock' *
- Caps lock key.
-
- `caps'
- Either shift key or caps lock key.
-
- `control', `ctrl' *
- Control key.
-
- `lalt', `left_alt' *
- Left alt key.
-
- `ralt', `right_alt' *
- Right alt key.
-
- `alt'
- Either alt key.
-
- `lcommand', `lamiga' *, `left_amiga' *, `left_command' *
- Left Amiga/Command key.
-
- `rcommand', `ramiga' *, `right_amiga' *, `right_command' *
- Right Amiga/Command key.
-
- `numericpad', `numpad' *, `num_pad' *, `numeric_pad' *
- This keyword *must* be used for any key on the numeric pad.
-
- `leftbutton', `lbutton' *, `left_button' *
- Left mouse button. See note below.
-
- `midbutton', `mbutton' *, `middlebutton' *, `middle_button' *
- Middle mouse button. See note below.
-
- `rbutton', `rightbutton' *, `right_button' *
- Right mouse button. See note below.
-
- `repeat'
- This qualifier is set when the keyboard repeat is active. Only
- useful for InputEvent class `rawkey'.
-
- Note: Commodities V37 has a bug which prevents the use of
- `leftbutton', `midbutton' and `rbutton' as qualifiers. This bug is
- fixed in V38.
-
-
- Key codes
- ==========
-
- Each InputEvent class has its own key codes:
-
-
- Key codes for InputEvent class `rawkey'
- ----------------------------------------
-
- Some keywords and synonyms were added to Commodities V38. These are
- marked with an `*'.
-
- `a'-`z', `0'-`9', ...
- ASCII characters.
-
- `f1', `f2', ..., `f10', `f11' *, `f12' *
- Function keys.
-
- `up', `cursor_up' *, `down', `cursor_down' *
- `left', `cursor_left' *, `right', `cursor_right' *
- Cursor keys.
-
- `esc', `escape' *, `backspace', `del', `help'
- `tab', `comma', `return', `space', `spacebar' *
- Special keys.
-
- `enter', `insert' *, `delete' *
- `page_up' *, `page_down' *, `home' *, `end' *
- Numeric Pad keys. Each of these key codes *must* be used with the
- `numericpad' qualifier keyword!
-
-
- Key codes for InputEvent class `rawmouse'
- ------------------------------------------
-
- These keywords were added to Commodities V38. They are not available
- in V37.
-
- `mouse_leftpress'
- Press left mouse button.
-
- `mouse_middlepress'
- Press middle mouse button.
-
- `mouse_rightpress'
- Press right mouse button.
-
- Note: To use one of these key codes, you must also set the
- corresponding qualifier keyword, e.g.
-
- rawmouse leftbutton mouse_leftpress
-
-
- Examples for Hot Keys
- ======================
-
- `ralt t'
- Hold right Alt key and press "t"
-
- `ralt lalt t'
- Hold left *and* right Alt key and press "t"
-
- `alt t'
- Hold either Alt key and press "t"
-
- `rcommand f2'
- Hold right Amiga key and press the second function key
-
- `numericpad enter'
- Press the Enter key on the numeric pad
-
- `rawmouse midbutton leftbutton mouse_leftpress'
- Hold middle mouse button and press the left mouse button
-
- `diskinserted'
- Insert a disk in any drive.
-
-
- ************ end of Stefan Becker's text *****************************
-
-
-
-
- appendix: tutorial / the supplied hotkey mapping
- ------------------------------------------------
-
- It is quite important for you to have a close look on the supplied example
- hotkey mapping of Angie, because only if you understand all of its hotkey
- definitions, you can be sure to know all the power of Angie and become
- familiar with the different commodities input descriptions you can use for
- your very personal Angie configuration.
-
-
- examples of the supplied mapping:
-
- ***
-
- 'lcommand esc' is mapped to '[^cd ram:¶newshell *]'
-
- I.e. every time you press the left amiga key plus the ESCape key, Angie
- starts a shell with the stack size Angie was started with, the task
- priority Angie was started with, the command path Angie was started with,
- the current directory assigned to 'ram:' and with the console Angie opened
- for the asynchronously launched process (the console window opens with
- optimized size and position on the default public screen). As the ToFront
- attribute ('^') is set for the AsyncDosSequence, the default public
- screen is immediately popped to the front.
-
- ***
-
- 'f7' is mapped to '^<control x>~80list lformat "%s%s"<left>\
- <left><left><left><left><left><left><left><left><left><left><left><left>\
- <left><left><left>'
-
- This definition already shows how to assign multiple actions to one single
- hotkey. It may be used in a shell: if you press f7, the active shell
- window is popped to front, any text that may be already typed in the
- command line is deleted (that's the effect of <control x>), then after a
- short delay of 80 milliseconds, the text 'list lformat "%s%s"' is inserted,
- and the cursor is positioned on the second space character after 'list'.
-
- Why that delay, you may wonder. The answer is as follows: The console is
- usually able to accept input events without any delay between them, yet
- there's the special <control x> case, where the console needs some dozens
- of milliseconds to recover, and all events that were inserted during this
- blackout are lost forever.
-
- ***
-
- 'f8' is mapped to '#200 <rawmouse leftbutton mouse_leftpress>\
- <rawmouse upstroke mouse_leftpress>'
-
- If you press the function key f8, two rawmouse input events are inserted
- into the input stream, with a 200ms delay between the insertions. The two
- events emulate a click on the left mouse button, with a click duration of
- 200 milliseconds: The first event is inserted for the downstroke event of
- the left mouse button whilst the second event signifies the upstroke event
- for the left mouse button.
-
- ***
-
- 'diskinserted' is mapped to '[if exists sys:utilities/say¶\
- sys:utilities/say "You've inserted a disk right now"¶endif]'
- with the NoFilter attribute set
-
- This definition has the effect that every time you insert a disk in one of
- your disk drives, and you have the 'sys:utilities/say' program of Workbench
- 2.04 along with the LIBS:translator.library & DEVS:narrator.device files
- installed, your Amiga tells you that you've just inserted a disk' The
- NoFilter attribute is set in order to supply all other commodities objects
- that are linked into the commodities network after this definition's object
- with the diskinserted event, too - otherwise all diskinserted events would
- be swallowed by this definition's commodities object.
-
- ***
-
- 'rawmouse leftbutton rightbutton mouse_rightpress' is mapped to
- '#100<rawmouse upstroke mouse_leftpress><lcommand shift l>' and
- 'lcommand shift -repeat l' is mapped to the '(ToBack)' action.
-
- NOTE: This definition only works if you have Workbench 2.1 or higher. The
- reason is as follows: Due to a bug, the commodities.library V37 of
- Workbench 2.04 ignores all 'leftbutton', 'midbutton' & 'rbutton' qualifiers
- when it searches for a matching input event. As a result, this hotkey
- would be triggered for every click on the right mouse button. However,
- this is intolerable. So, in the above definition the 'rbutton' qualifier
- has been replaced by the 'rightbutton' qualifier, which commodities.library
- V37 cannot parse. Thus this hotkey definition is ignored by Angie for
- Workbench 2.04 systems.
-
- The first definition is a magic to bring a window to back by pressing the
- left mouse button, and while keeping the left mouse button pressed,
- clicking the right mouse button. THIS DEFINITION EVEN WORKS IF YOU HAVE
- THE AUTO HUNT ENABLED, if you have small 'Stable time' and 'Snoop delay'
- values (Otherwise just replace the '#100' by '#200' etc). Have a close
- look at this definition, especially at the <rawmouse upstroke
- mouse_leftpress> event! Every time you have a rawmouse hotkey where the
- leftbutton qualifier is specified without the mouse_leftpress keycode, and
- you want to assign an Intuition window action to that hotkey, you are
- advised to do it like here: Map two input events (or solely the above
- mentioned <rawmouse upstroke mouse_leftpress>-Event plus a short delay plus
- the other actions) to the hotkey, with the first event inserted the
- <rawmouse upstroke mouse_leftpress> event, and the second one an event that
- Angie has assigned to the Intuition action itself. This is because
- otherwise, WORKBENCH windows react in a very sluggish way to such a hotkey.
- This is in no way due to Angie, but thoroughly to Intuition. The 100 ms
- delay in this particular definition is for evading problems with Angie's
- Auto-Hunt device and is usually not needed.
-
- The second definition ('lcommand shift -repeat l') shows how to define
- normal rawkey hotkeys within Angie: If you press the left amiga key,
- shift and 'l', the active window is brought to the back of its screen.
-
- ***
-
- 'lcommand shift -repeat z' is mapped to the '(Zip)' action &
- 'lcommand -repeat z' is mapped to the '(^Zip)' action.
-
-
- These definitions are two normal rawkey type definitions that both cause
- the active window to zip its position. For the second definition, the
- active window also immediately pops to the front (and is hunted, if the
- global 'Hunt on wintofront hotkeys' feature is selected), as the ToFront
- attribute is set. If you have the global 'Hunt always' switch turned on
- however, the active window is always popped and hunted, even if you press
- the first hotkey.
-
- Note the specified '-repeat' qualifier in the definition. It has the
- effect that if you keep the 'z' key pressed, the repeated presses are also
- included in the hotkey definition. 'BUT', you may complain, 'I only get a
- Zip action ONCE even if I keep the 'z' key pressed.' Cool down, dude, this
- is right, and is due to Angie: By default, Angie swallows all hotkey
- presses, that have the 'repeat' qualifier set. In order to inhibit this
- for one specific hotkey, just set the 'Repeatbl' attribute for that hotkey,
- and all hotkey presses matching that hotkey's input description are
- processed by Angie, even those that have the 'repeat' qualifier set.
-
- ***
-
- 'lcommand -shift -repeat help' is mapped to the '(^HuntWindow)' action with
- the NoScrAct attribute set and
- 'lcommand lamiga_press' is mapped to the 'NoKeyActivate' pseudo action with
- the NoFilter, NoScrAct & Repeatbl attributes set.
-
- The first definition is a rawkey hotkey definition with an extraordinary
- characteristic: The NoScrAct attribute is set for this hotkey. This has
- the effect that even if the active window's screen is completely hidden,
- and one or more other visible screens with windows exist, and the global
- 'Key screen activation' function is active, triggering this hotkey does NOT
- CAUSE A 'KEY SCREEN ACTIVATION' ACTION. Thus, if you have an active window
- on another screen, and that screen is completely invisible, you can press
- lcommand help to hunt that active window. Without the NoScrAct attribute,
- pressing help would activate a new window on one of the visible screens and
- hunt the new active window, which would be rubbish. If the second hotkey
- wasn't defined, the same nonsense operation would happen if you pressed the
- lcommand qualifier key (see next example for more).
-
- ***
-
- 'lcommand lamiga_press' &
- 'lcommand -repeat -caps -alt -control m' &
- 'lcommand -repeat -caps -alt -control n' are all mapped to
- the 'NoKeyActivate' pseudo action with the NoFilter, NoScrAct & Repeatbl
- attributes set.
-
- These definitions are special in several ways: First, the 'NoKeyActivate'
- action is a pseudo action, i.e. it does not trigger any action. Second,
- the NoFilter, NoScrAct & Repeatbl attributes are enforced for this pseudo
- action: All matching input events are kept from triggering 'Key screen
- activation' action, even if all conditions for that action are given (see
- the last example for more).
-
- The last two input descriptions represent the normal Intuition hotkeys for
- shuffling screens respectively for popping the Workbench screen to front.
- Why should these events be kept from triggering 'Key screen activation'
- action, you may ask, and the answer is as follows: it is usually
- undesirable to have a key screen activation action triggered for hotkeys
- that shuffe screens without activating a window of the new frontmost
- screen, no matter whether these hotkeys are defined inside (simply set the
- NoScrAct attribute for the hotkey in that case) or outside Angie.
-
- The first description keeps all simple key presses of the left amiga key
- from causing Key Screen Activation action. This may be useful because most
- hotkey definitions of the supplied Angie configuration (and the 'lcommand
- m/n' Intuition screen shuflling hotkeys!) include the lcommand qualifier.
- If you want to keep these hotkeys from triggering key screen activation by
- setting the NoScrAct attribute, this would have no effect if the 'lcommand
- lamiga_press' key was not mapped to the 'NoKeyActivate' pseudo action, as
- pressing the left amiga key would originate the Key Screen Activation
- action.
-
- ***
-
- Now, apprentice, go and create your very personal Intuition interface!;-)
-
-
-
- FOR MORE HOTKEY EXAMPLES, IN CONNECTION WITH THE SETACTIVEWIN UTILITY &
- SYNCDOSSEQUENCES, HAVE A LOOK AT THE DOCUMENTATION OF SETACTIVEWIN!!!
-
-
-
-
- PS: This documentation was written in a few hours and has not been
- completely checked for typos & mistakes yet - so don't blame me if you find
- many mistakes - keep in mind that English is not my native language;-)
-
-
-
-